home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / pcboard / news11r0.zip / NEWSPPER.DOC < prev    next >
Text File  |  1994-06-01  |  24KB  |  522 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                                 NEWSPAPER v1.1
  15.                                 ~~~~~~~~~~~~~~
  16.  
  17.                 A System News File Display Utility for PCBoard
  18.  
  19.                              by George Silberstern
  20.  
  21.  
  22.                             U S E R S   M A N U A L
  23.                             ~~~~~~~~~~~~~~~~~~~~~~~
  24.  
  25.  
  26.  
  27.     Page i                                                   Newspaper v1.1
  28.     ───────────────────────────────────────────────────────────────────────
  29.  
  30.  
  31.     Distribution Archive
  32.  
  33.     The following files should have been included in the archive containing 
  34.     this program: 
  35.  
  36.                 NEWSPPER PPE - The Newspaper Utility for PCBoard
  37.                 NEWSPPER INI - A sample Configuration file
  38.                 NEWSPPER DOC - This file: The User's Manual
  39.                 REVISION INF - List of changes made to Newspaper
  40.                 FILE_ID  DIZ - Description file Bulletin Boards
  41.  
  42.     If any of these files are missing, then you may not have an original 
  43.     copy of the archive.
  44.  
  45.  
  46.     Distribution
  47.  
  48.     Newspaper is being released as Shareware.  You may distribute the 
  49.     program freely, as long as you do not alter the program in any way 
  50.     (that includes disassembly, and reverse engineering).  It would also be 
  51.     greatly appreciated if you distributed the archive unchanged.  That is, 
  52.     containing all of the files listed at the start of this document. 
  53.  
  54.     
  55.     License and Registration
  56.  
  57.     You are authorized to use Newspaper for a thirty (30) day period for 
  58.     the purpose of evaluation.  If you like the program and choose to use 
  59.     it after this period, you are required to register your copy.  
  60.     
  61.     Registered owners of Newspaper will receive a Key Code that will enable 
  62.     additional features that have been, and will be added in the future.  
  63.     In addition, registered users are entitled to receive a discount when 
  64.     registering any other software I author(ed).  Finally, you'll also have 
  65.     the satisfaction of knowing that you're helping to support the 
  66.     availability of inexpensive software.  At $10 (US), that isn't asking 
  67.     for too much.
  68.     
  69.     Of course, if you believe Newspaper to be worth more than $10, I won't 
  70.     stop you from sending in a higher amount! <grin> 
  71.     
  72.     Please make your check payable to GEORGE SILBERSTERN, and mail it to 
  73.     the following address: 
  74.                                George Silberstern
  75.                                1 Makefield Road  #E-184
  76.                                Morrisville, Pa  19067
  77.  
  78.     Don't forget to also include the Order Form that appears at the end of 
  79.     this manual! 
  80.  
  81.  
  82.     Newspaper v1.1                                                  Page ii
  83.     ───────────────────────────────────────────────────────────────────────
  84.  
  85.  
  86.     Finding the Author
  87.  
  88.     If you need to get in touch with me directly, you may call my system, 
  89.     NETRef BBS at 215/736-1889.  You can connect at 300-14400 Bps (USR DS). 
  90.     Once your account has been validated (done online), you will be able to 
  91.     leave me a message.  If you have access to Fidonet, you can send a 
  92.     Netmail message to me at 1:273/214.  If you have a problem running 
  93.     Newspaper, please be specific about it in your message and leave a 
  94.     means to contact you.  I will get in touch just as soon as I'm able to. 
  95.  
  96.     If you call my BBS and wish to find the latest release of this, or any 
  97.     other software I have written for public release, they can be found in 
  98.     the File Area #1, "SOFTWARE AUTHORED BY THE SYSOP", off the Main Board.
  99.     If you have access to a FidoNet site, you can always File Request the 
  100.     program from 1:273/214.  A complete list of files available online is 
  101.     always available using the Magic Name, FILES.
  102.  
  103.  
  104.     Page iii                                                 Newspaper v1.1
  105.     ───────────────────────────────────────────────────────────────────────
  106.  
  107.  
  108.     Warranty and Copyright Information
  109.  
  110.          The author of this program shall not be held responsible 
  111.          or accountable, under any circumstance, for the behavior 
  112.          or performance of the program.  Furthermore, neither the 
  113.          author, or any party given permission to distribute this 
  114.          program, shall be held liable or responsible for damages 
  115.          incurred, including the incidental or consequential loss 
  116.          of data, equipment or income, that may result from usage 
  117.          or inability to use this program.  This also implies any 
  118.          data rendered inaccurate, and/or loss sustained by third 
  119.          parties.  These terms apply in all cases and situations,
  120.          even if the author has been advised of the possibilities
  121.          of such damages, or for any claims by any other parties.
  122.  
  123.     All the programs, products, and features thereof, that are mentioned in 
  124.     this documentation, are copyrighted and/or trademarked by their 
  125.     respective owners and authors.  Please refer to the documentation of 
  126.     each product to determine the actual copyright and/or trademark 
  127.     owner(s).  Errors, or omissions are unintentional.
  128.  
  129.  
  130.     Beta Testing Information
  131.  
  132.     Interested in being a Beta Tester?  The author is looking for up to 
  133.     five (5) SysOps who would like to offer their systems as Beta Test 
  134.     sites for his utilities.  The basic requirements are that you must run 
  135.     PCBoard v15, and that you keep a record of any problems or anomalies 
  136.     you experience.  For more information, leave a comment on the author's 
  137.     BBS, or if you're a Fido site, send Netmail to the author (see the 
  138.     section "FINDING THE AUTHOR" elsewhere in this manual for contact 
  139.     information).
  140.  
  141.  
  142.     Notes of Appreciation
  143.  
  144.     A special "Thank You" goes to the following SysOps for registering 
  145.     Newspaper:
  146.  
  147.     Bob French                  EARNET BBS                     407/380-9626
  148.     John Cheever                Mr. C's BBS                    619/446-4452
  149.     James Morris                The BreadBoard II              206/881-5927
  150.  
  151.  
  152.     Newspaper v1.1                                                  Page iv
  153.     ───────────────────────────────────────────────────────────────────────
  154.  
  155.  
  156.     About the Author
  157.  
  158.     George Silberstern was born and raised in Quito, Ecuador (South 
  159.     America).  He took a passing interest in Computer Science while in High 
  160.     School.  Computers became his hobby (ie. vice) while in College, where 
  161.     he majored in Communications and Foreign Languages, and during his 
  162.     Freshman year, in 1984, discovered Telecomputing and started his first 
  163.     BBS.  George has also taught himself several Computer programming 
  164.     languages.  In 1987, George began consulting on a freelance basis, 
  165.     primarily developing custom database applications using Clipper. 
  166.  
  167.     In 1990, he started NETRef BBS, in order to provide product support for 
  168.     his clients, and as a place where users can obtain help with hardware 
  169.     and software problems.  In 1991, NETRef BBS became a member of FidoNet, 
  170.     and shortly thereafter became the first United States support site 
  171.     for FidoPCB, a Fido to PCBoard Message format converter originating in 
  172.     Europe.
  173.  
  174.  
  175.     Page v                                                   Newspaper v1.1
  176.     ───────────────────────────────────────────────────────────────────────
  177.  
  178.  
  179.     Other Programs
  180.  
  181.     The following programs written by the author, have been released as 
  182.     Shareware, and can be found on Bulletin Boards around the world.  They
  183.     can also be found on the author's own BBS:
  184.     
  185.        AutoClip - Automates editing, compiling and debugging of 
  186.                   applications written with Clipper's Summer '87 release
  187.        NetSend  - A Mail Transfer script for use in message exchanges via 
  188.                   Mark Findlay's NETMAIL Echo Net manager for PCBoard v14.5 
  189.                   or earlier.  Allows Nodes to do unattended Mail transfers 
  190.                   using Procomm Plus.
  191.        Cntax    - A Syntax Checker for C/C++ Source Code.  Checks for 
  192.                   matching Grouping Symbols and Quote Mark pairs.  Works 
  193.                   with any flavor of C and C++.  Current release: v3.0
  194.        Enviro   - The DOS Environment Inspector.  Displays allocation and 
  195.                   usage information on the DOS environment buffer, as well 
  196.                   as its content.  Ideal for assisting in the tracking down 
  197.                   what is lost due to the DOS "Out of Environment Space" 
  198.                   Error message, and/or for identifying unnecessary data in 
  199.                   the buffer.  Current release: v3.0
  200.        R.A.T.S. - Short for Recorded media Archive Tracking System, this is 
  201.                   a powerful database system that keeps track of all 
  202.                   recorded media in your library, including Records, Tapes, 
  203.                   CD's and Videocassettes.  Entries have both brief and 
  204.                   extended description capabilities.  An integrated 
  205.                   reporting system is included.  Current release: 3.10
  206.        FPBlt    - A Mail Traffic Summary bulletin generator for use with 
  207.                   the FidoPCB Mail Tossing software by Matjaz Koce, and
  208.                   PCBoard v14.5 or later.  Current release: v1.0
  209.  
  210.  
  211.     Newspaper v1.1                                                   Page 2
  212.     ───────────────────────────────────────────────────────────────────────
  213.  
  214.  
  215.     I] - Introduction to Newspaper
  216.  
  217.     Newspaper is, in simple terms, a News File display utility for use by 
  218.     SySops running PCBoard v15.1 or later.  Unlike most other News File 
  219.     generators available today, Newspaper is very easy to set up and run. 
  220.     Preparation consists of editing the Configuration File, configuring 
  221.     PCBoard to execute the PPE, Creating the text file that will be 
  222.     displayed by the PPE, and a dummy file to handle non-commandline 
  223.     situations.  In short, reading this Users Manual is a more involved 
  224.     than getting the PPE up and running is.  But don't take that as an 
  225.     excuse not to read this thoroughly at least once...
  226.  
  227.     The Newspaper utility was created using Clark Development's PPLC 
  228.     Compiler, and this is the reason why it will not work with either 
  229.     versions of PCBoard prior to v15.1, or BBS software other than PCBoard.
  230.  
  231.  
  232.  
  233.     Page 3                                                   Newspaper v1.1
  234.     ───────────────────────────────────────────────────────────────────────
  235.  
  236.  
  237.     II] - Release Notes
  238.  
  239.     Newspaper is being released as Shareware.  In its unregistered format, 
  240.     the program has the same functional capabilities as its registered 
  241.     counterpart, but there are a few behavioral differences between them.  
  242.     Quite simply, the unregistered version of Newspaper will display the 
  243.     news file in one color only, regardless of the parameters contained in 
  244.     the configuration file.  In addition, a "beg" message is displayed with 
  245.     an extended pause at the end of the program, and the number of lines 
  246.     per screenful is hard coded. 
  247.  
  248.     The registered version of Newspaper eliminates the "beg" message and 
  249.     its associated delay, will base the screen size based on the setting of 
  250.     each individual user's Page Length setting, and has the ability to 
  251.     display the news file with colors defined by the SysOp.
  252.  
  253.     Registration also entitles you to future upgrades of Newspaper, with 
  254.     all of its features enabled, because any features that may be added 
  255.     down the line, will not be accessible to unregistered users.  But 
  256.     enough with the hoopla!  A registered version of Newspaper can be yours 
  257.     for a mere $5.00 (US).  Yes, you read correctly:  Five US Dollars, and 
  258.     you're the proud owner of a copy of Newspaper for life!
  259.  
  260.  
  261.     Newspaper v1.1                                                   Page 4
  262.     ───────────────────────────────────────────────────────────────────────
  263.  
  264.  
  265.     III] - Installing Newspaper
  266.     
  267.     a) Requirements:  As stated, you need to be running PCBoard v15.  You 
  268.        will also need a Text File Editor such as QEdit, PCWrite, or EDLIN 
  269.        (urgle).  Finally, you need to decide where the PPE files will be 
  270.        stored and executed from.
  271.  
  272.     b) Preparation (PPE):  Copy the NEWSPPER.PPE and NEWSPPER.INI files 
  273.        into the directory of your choice (where you park all your PPE's is 
  274.        fine too).  Next, with your Text Editor, edit the NEWSPPER.INI 
  275.        file.  It contains four lines, as follows: 
  276.  
  277.          °  1] Name to display as part of the Registration message
  278.             2] Must be all zeroes (0) -sixteen in all- or contain the
  279.                validation key provided by the author
  280.             3] The full path and name of the file to be displayed
  281.          °  4] The base Color Set used to display the file.  It is also 
  282.                used to draw the borders of each screen.  This color 
  283.                code must be a valid PCBoard @X color macro
  284.          °  5] The secondary color set used in displaying the file.  It 
  285.                is used as an alternate color for displaying News File 
  286.                text on each screenful.  This color code must be a valid 
  287.                PCBoard @X color macro
  288.          °  6] The border trim used on the left side of the News File,
  289.                on lines adjoining the 'page separator' lines
  290.          °  7] The border trim used on the left side of the News File,
  291.                on all other lines
  292.          °  8] The border trim used on the right side of the News File,
  293.                on lines adjoining the 'page separator' lines
  294.          °  9] The border trim used on the right side of the News File,
  295.                on all other lines
  296.          ° 10] The Leftmost character of the Dividing Line (1 char limit)
  297.          ° 11] The Rightmost character of the Dividing Line (1 char limit)
  298.          ° 12] The Character used to make up the Inner part of the Dividing
  299.                line (1 char limit)
  300.            13] Clear Screen Flag.  If set to "Y" (no quotes), the screen 
  301.                will be cleared first. The default is no screen clearing
  302.  
  303.        ° Enabled in the Registered version only
  304.  
  305.     c) Preparation (PCBoard):  To make Newspaper work, you need to load 
  306.        PCBSetup.  Choose Main Menu option B (File Locations), and from this 
  307.        submenu, select option B (Configuration Files).  Highlight the line 
  308.        identified as "Name/Loc of Default CMD.LST" and press <F2>.
  309.  
  310.  
  311.     Page 5                                                   Newspaper v1.1
  312.     ───────────────────────────────────────────────────────────────────────
  313.  
  314.  
  315.            - Enter 'NEWS' in the Commands column (sans quotes)
  316.            - Enter the security level of your choice in the
  317.              Security column
  318.            - Enter the drive, path and PPE name (plus extension)
  319.              in the PPE/MNU File column
  320.            - Save the modified CMD.LST file
  321.        
  322.        The above will take care of those instances where a user on the BBS 
  323.        enters the NEWS command to view the file you specified in the 
  324.        configuration file.  But this doesn't cover those situations where 
  325.        PCBoard displays the file of its own volition.  This is where the 
  326.        dummy file that was mentioned previously comes in. 
  327.  
  328.        As you know, every conference has an option that defines the name 
  329.        and location of the News File.  PCBoard does not permit you to 
  330.        replace this information with a PPE execution command.  If you 
  331.        specify the text file used by the PPE, it will be displayed as-is. 
  332.        Therefore, enter the name of a Dummy file.  This Dummy file can 
  333.        contain any text you want, but at the very least, must have a single 
  334.        line that invokes the PPE.  It can also include leading and/or 
  335.        trailing text for display prior to, or after running the PPE.  The 
  336.        required line has to be structured as follows: 
  337.  
  338.                           !<ppe-pathspec>\<ppe-filename>.PPE
  339.  
  340.        The ".PPE" extension is mandatory, as is the initial "!".  This file 
  341.        and the path to it, are what must be specified in the aforementioned 
  342.        News File Name/Path field in the configuration screen for each 
  343.        conference.
  344.  
  345.     d) Caveats:  There are two items that require special attention at this 
  346.        point, because they relate to how Newspaper performs. 
  347.        
  348.        - Any text preceeding or following the invocation of the PPE in 
  349.          automatic mode will only be displayed in this situation.  This 
  350.          text will not be displayed when a user issues the NEWS command, 
  351.          because it goes straight to the PPE.  At this point it is 
  352.          something that cannot be changed.
  353.        - The Configuration File naming convention is hard coded to use the 
  354.          PPE filename as a prefix, and an INI extension.  Anything else 
  355.          will cause an error when running the PPE.  This is something that 
  356.          may be altered in a future release
  357.  
  358.     This completes the installation of Newspaper on your BBS system.  All 
  359.     that remains to be done, is to write your news message.
  360.  
  361.  
  362.     Newspaper v1.1                                                   Page 6
  363.     ───────────────────────────────────────────────────────────────────────
  364.  
  365.  
  366.     IV] - Writing the News File
  367.  
  368.     Installing and using Newspaper does you no good unless you have a file 
  369.     for it to display.  This section of the manual is meant to guide you in 
  370.     creating the input file that will be displayed by Newspaper. 
  371.  
  372.     To create the input file, you should use an ASCII text editor.  In 
  373.     theory, you can also use a program like WordPerfect or Word, but if you 
  374.     do this, you need to remember that the file must be saved as ASCII 
  375.     text, and that the text has to be Left Justified to Column one.
  376.  
  377.     If you're in real dire straits and use EDLIN to write the file, the 
  378.     author feels sorry for you.  Seriously, if you do wind up using EDLIN 
  379.     you have to be even more careful to keep the lines to the 66 character 
  380.     maximum, as it offers absolutely no control over margins.  A Text 
  381.     Editor goes a long way toward keeping your text within this limitation, 
  382.     and is worth considering, especially when you take into account that 
  383.     many are Shareware, or even Freeware.
  384.  
  385.     Whichever program or utility you use to write the input file, you 
  386.     should be aware that the maximum useable width of each line, is 66 
  387.     (sixty six) characters.  Any characters after the 66th column position 
  388.     will be ignored.  The only exception to this rule applies when @X macro 
  389.     codes are detected, they will be stripped out before Newspaper extracts 
  390.     the 66 character block.  Save the file to the name and location 
  391.     specified in the Configuration file.  You're now set to go.
  392.  
  393.  
  394.     Page 7                                                   Newspaper v1.1
  395.     ───────────────────────────────────────────────────────────────────────
  396.  
  397.  
  398.     V] - How it all works
  399.  
  400.     Since this is the author's first attempt at writing a PPE, and was 
  401.     written cold turkey, a description of its operation follows.  This is 
  402.     meant to illustrate how easy it is to create a PPE.
  403.  
  404.     The first thing Newspaper does after loading, is test if the 
  405.     Configuration file exists.  If it can't be found, an error message will 
  406.     be displayed and execution ends.  The same procedure applies when 
  407.     Newspaper looks for the Input file, because in both instances, the PPE 
  408.     won't be able to run correctly.  These errors are written to the Log 
  409.     file.
  410.  
  411.     Next, the PPE will determine the Page Size as set in the caller's 
  412.     account configuration, the color scheme, and adapt the number of lines 
  413.     in the page size (Newspaper relies on an even number of lines per 
  414.     screen).  Other determinations are made at this time as well, and some 
  415.     of these apply to the Registered version only.
  416.  
  417.     The actual processing by the PPE begins by building those strings which 
  418.     are used by the PPE without modifications.  It also checks the input 
  419.     file to determine its length.  At this point, Newspaper begins creating 
  420.     the formatted News File.  This is a continuous loop which begins with a 
  421.     fixed header.  After the header, the input file is read, line by line, 
  422.     tested for @X codes (which get stripped) and length (again, up to 66 
  423.     characters), before being formatted, on the fly, for output.  If a line 
  424.     is found to be less than 66 characters, it is filled with blanks 
  425.     automatically.
  426.     
  427.     This cycle continues until the maximum number of lines per screen is 
  428.     reached, and a fixed footer is inserted.  Finally the user is given a 
  429.     MORE prompt, at which s/he can eithe continue viewing the file, or 
  430.     cancel the display.  If the user chooses to view the entire file, the 
  431.     entire process repeats itself until the entire input file has been 
  432.     read, and displayed in formatted mode to the caller.
  433.     
  434.     Upon completion, control is passed right back to PCBoard, except if 
  435.     your copy of Newspaper is not registered.  Unregistered versions will 
  436.     advertise themselves as such, and pause briefly before passing control 
  437.     to the BBS.  Execution is recorded in the Caller Log.
  438.  
  439.  
  440.     Newspaper v1.1                                                   Page 8
  441.     ───────────────────────────────────────────────────────────────────────
  442.  
  443.  
  444.     VI] - Error Messages
  445.  
  446.     Any serious Errors are not only displayed to the caller, but also 
  447.     recorded in the Caller Log.  Newspaper can record the following errors 
  448.     if they are detected:
  449.  
  450.     ERROR: [1] Unable to read <filename>
  451.        Displayed if Newspaper cannot locate <filename>.  This would be
  452.        if the file doesn't exist, is not in the specified directory,
  453.        or isn't identified with the specified name.
  454.  
  455.     ERROR: [2] Unable to open <filename>
  456.        Displayed when PCBoard cannot open one of the files used by the
  457.        PPE.  This could happen in a multiuser environment, if more than
  458.        one Node tries to access the same file at exactly the same time,
  459.        or in similar situations.
  460.  
  461.  
  462.     Page 9                                                   Newspaper v1.1
  463.     ───────────────────────────────────────────────────────────────────────
  464.  
  465.  
  466.     USER NOTES:
  467.  
  468.                   NEWSPAPER v1.1 - PCBoard News File Utility
  469.                                   Order Form
  470.  
  471.  
  472.  
  473.     MAIL TO:
  474.  
  475.     George Silberstern
  476.     1 Makefield Rd #E-184
  477.     Morrisville, Pa 19067-5011
  478.  
  479.  
  480.          Your Name: _______________________________________________
  481.  
  482.     Address    (1): _______________________________________________
  483.  
  484.     Address    (2): _______________________________________________
  485.  
  486.     City/State/Zip: _______________________________________________
  487.  
  488.         Home Phone: _________________________________
  489.  
  490.  
  491.  
  492.  
  493.  
  494.           BBS Name: _______________________________________________
  495.                     (Exactly as it appears in the PCBOARD.DAT file)
  496.                         (Please use mixed case if applicable!!)
  497.  
  498.          BBS Phone: _________________________________
  499.                        (Main Public Access Number)
  500.  
  501.  
  502.     
  503.     Ammount enclosed: $________________
  504.  
  505.     Checks or Money Orders should be drawn on United States funds
  506.     exclusively, and be made payable to GEORGE SILBERSTERN.  Foreign
  507.     checks should be drawn on a United States branch or bank, or
  508.     include a $10 handling surcharge.  Do NOT send cash!
  509.  
  510.  
  511.  
  512.           INCOMPLETE ORDERS CANNOT BE PROCESSED AND WILL BE RETURNED
  513.  
  514.  
  515. --------------------------------------------------------------------------------
  516.                              For Office Use Only!
  517.     
  518.        RDate: ________  Key Code: _____________________  SDate: ________
  519.  
  520.                                   _____________________
  521.  
  522.